Devices, configuration, and state
Device registration
In order for a device to connect, it must first be registered in the device manager. The device manager lets you create and configure device registries and the devices within them. The device manager can be used through the Cloud Platform Console, or the REST-style API.
Device registries
A device registry is a container of devices.
- Each device registry is created in a Omnicore Subscription, and belongs to that subscription.
- A registry is identified in the Omnicore service by its full name as: subscription/{subscription-id}/registries/{registry-id}.
- The device registry is configured with one or more Cloud Pub/Sub or AWS Kinesis topics to which telemetry events are published for all devices in that registry. A single topic can be used to collect data across all regions.
- Monitoring is automatically enabled for each registry.
- For information on device registry ID naming and size requirements, see Permitted characters and size requirements.
Devices
When you create a device within a registry, you define the device as a OmniCore resource. You can then view device details and control some properties.
- A device can be blocked from communicating with OmniCore. This can be useful when a sensor fails or a device is misconfigured.
- Device timestamps show the most recent heartbeat and telemetry event received.
- Each device can be identified by its full resource name: subscription/{subscription-id}/registries/{registry-id}/devices/{device-id}
Device metadata
You can define metadata for a device, such as hardware thumbprint, serial number, manufacturer information, or any other attribute. OmniCore does not interpret or index device metadata. In theory, device metadata is more secure than device state or device configuration because device metadata is never sent to or from a device. This means that, if a device is compromised, the device metadata cannot be read.
Device metadata shouldn't change often; for best results, update it no more often than once per day.
You can define up to 500 key-value pairs when you add or edit a device. Each key must be unique.
For information on device metadata key-value naming and size requirements, see Permitted characters and size requirements.
Device configuration
With OmniCore, you can control a device by sending it a device configuration. A device configuration is an arbitrary user-defined blob of data sent from OmniCore to a device. The data can be structured or unstructured. It can also be of any format, such as arbitrary binary data, text, JSON, or serialized protocol buffers.
Device configuration is persisted in storage by OmniCore. The maximum size for configuration data is 64 KB. For additional limits, see Quotas and Limits.
For best results, a device configuration should focus on desired values or results, rather than on a sequence of commands.
Configuration versions
MQTT bridge
For a given MQTT connection, a device receives configurations only the latest version. OmniCore versions by datetime field and do not maintain a specific version number for configurations.
Note that a device is not guaranteed to receive every configuration update; rather, it will always receive the latest update. If a configuration is being updated rapidly, devices may not receive intermediate versions.
HTTP bridge
Devices connecting over HTTP receives only the most recent version, as described in the section on the HTTP bridge
Device state
Device state information captures the current status of the device, not the environment. Devices can describe their state with an arbitrary user-defined blob of data sent from the device to the cloud. The data can be structured or unstructured. It can also be of any format, such as binary data, text, JSON, or serialized protocol buffers.
Some examples of device state include the health of the device or its firmware version. Typically, device state information is not updated frequently.
Differences between device metadata, configuration, and state
Using configuration and state together, you can answer questions like: What does the device currently "think" it should be doing? How does that compare to the most recent configuration for the device? In contrast, metadata serves primarily as a label or identifier for devices.
Configuration data is sent to the device from OmniCore. State data is sent by the device to OmniCore. You can think of configuration as an external instruction sent to a device, and of state as a device's internal representation. Configuration and state data can have the same schema and encoding, or they can be different.
Information that needs to be sent to or from a device should not be stored as device metadata because device metadata stays in the cloud. That information should be in a device configuration if you need to send it to a device, or in device state data if you need to report it back to OmniCore.
The following example explains the different uses of metadata, configuration, and state using the scenario of devices in a building:
Suppose that you have several devices on each floor in a building. To identify devices on the seventh floor, you could add a 'floor': '7' metadata key-value pair to the devices on the seventh floor. Applying this metadata information provides a way of identifying the devices, but because metadata is not interpreted or indexed, the metadata can only be used for identification purposes.
If you wanted to change the state of the devices in the building, you could send a device configuration to each device. This configuration would comprise an arbitrary blob of data that contains the desired temperature for the device as well as whether the device's lights are turned on or off:
{
temperature: 50
lights: off
}
The configuration alone does not change the temperature of the device or turn its lights on or off; it is up to the device to interpret the configuration and use its own logic to carry out the command. Over the next several hours, the device configuration will not change (unless you update and send a new configuration), but the device's state should change as the temperature increases or decreases and the device turns its lights off.
- To verify that the configuration was correctly applied and that the devices are in the correct state, each device can report its state (whether it's on or off, what its temperature is, and that its temperature is less than or equal to 50 degrees) to Cloud IoT Core.
The following table shows the main differences between device metadata, configuration, and state:
| Device metadata | Device configuration | Device state | |
|---|---|---|---|
| Description | Defines and classifies devices | - Updates a device's state by sending the expected state as a configuration - Controls a device by providing commands in a configuration | Captures the current state of a device |
| Content | Key-value string pairs | Arbitrary user-defined blob of data | Arbitrary user-defined blob of data |
| Limitations | Keys:
Maximum combined total size of all device metadata key-value pairs: 256 KB |
|
|
| Use cases | Store a device's serial number and manufacturer information as a key-value pair |
| Retrieve a device's health (such as the frequency of crashes) |
| Message direction | None | Omnicore to device | Device to Omnicore |
| Recommended frequency | No more often than once per day per device | Less than 0.1 QPS | Less than 0.1 QPS |
Changing device behavior or state using configuration data
As noted in the table above, the primary use cases of configuration data are as follows:
- Sending a device's expected state as a configuration
- Sending a command to a device
Sending the desired state as configuration data
Device configuration data stored in Cloud IoT Core can be used to change the state of a device. For example, suppose the configuration of a device is represented as follows:
{
firmwareVersionRequest: 1.11
}
Your MQTT or HTTP client could interpret this configuration data as instructions for changing the device's state — in this case, check that the device is on firmware version 1.11. The device can then send its state to Cloud IoT Core to show which firmware version it has:
{
firmwareVersion: 1.11
}
Modeling commands using configuration and state data
Device configuration data stored in Cloud IoT Core can be used to model device commands. For example, suppose the configuration of a device is represented as follows:
{
rebootRequested: true
}
Your MQTT or HTTP client could interpret this configuration data as instructions to execute actions — in this case, send a reboot command. The device can then show the results by reporting its state and showing that one second has elapsed since its last reboot:
{
last_reboot: 1
}
Structuring configuration data
Configuration data can also be more structured and can include details about the expiration of commands:
{
commands: {
id1: {
type: REBOOT
requestedTimestamp: xxxx
expirationTimestamp: yyyy
}
id2: ...
}
}
Your client could read these commands and update the device state accordingly, supplying a timestamp for the reboot, and potentially an error message.
{
commandResults: {
id1: {
type: REBOOT
completedTimestamp: zzzz
errorMessage: >empty<
}
id2: ...
}
}
This model can be thought of as a command-and-response relationship between the client and devices. If expiration time is used, make sure the device's clock is synchronized.